home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_1.3 / Autodocs1.3 / DevicesL-Z / narrator.doc < prev    next >
Encoding:
Text File  |  1988-10-17  |  9.2 KB  |  303 lines
  1. TABLE OF CONTENTS
  2.  
  3. narrator.device/AbortIO
  4. narrator.device/CloseDevice
  5. narrator.device/CMD_FLUSH
  6. narrator.device/CMD_READ
  7. narrator.device/CMD_RESET
  8. narrator.device/CMD_START
  9. narrator.device/CMD_STOP
  10. narrator.device/CMD_WRITE
  11. narrator.device/OpenDevice
  12.  
  13.  
  14. narrator.device/AbortIO               narrator.device/AbortIO
  15.  
  16.     NAME
  17.         AbortIO - Abort an IO request
  18.  
  19.     SYNOPSIS
  20.         AbortIO(iORequest)
  21.                     A1
  22.  
  23.     FUNCTION
  24.         Aborts a speech IO request.  The request may be in the queue
  25.        or currently active.
  26.  
  27.     INPUTS
  28.         iORequest - pointer to the IORequest block of request to abort.
  29.  
  30.     RESULTS
  31.         io_Error field of IORequest set to IOERR_ABORTED
  32.  
  33.     BUGS
  34.  
  35.     SEE ALSO
  36.         narrator.device/BeginIO, exec/io.h 
  37.  
  38. narrator.device/CloseDevice
  39.  
  40.     NAME
  41.         CloseDevice - terminates access to the narrator device
  42.  
  43.     SYNOPSIS
  44.         CloseDevice(iORequest)
  45.                         A1
  46.  
  47.     FUNCTION
  48.         Close invalidates the io_Unit and io_Device fields in the
  49.         IORequest, preventing subsequent IO until another OpenDevice.
  50.         CloseDevice also reduces the open count.  If the count 
  51.         goes to 0 and the expunge bit is set, the device is 
  52.         expunged.  If the open count goes to zero and the delayed
  53.         expunge bit is not set, CloseDevice sets the expunge bit.
  54.  
  55.     INPUTS
  56.         iORequest- pointer to an IORequest block
  57.  
  58.     RESULTS
  59.         The unit and device pointers of the IORequest block are invalidated.
  60.  
  61.     BUGS
  62.  
  63.     SEE ALSO
  64.         narrator.device/OpenDevice, exec/io.h
  65.  
  66. narrator.device/CMD_FLUSH                 narrator.device/CMD_FLUSH
  67.  
  68.     NAME
  69.         CMD_FLUSH - Aborts all inprogress and queued requests
  70.  
  71.     FUNCTION
  72.         Aborts all in-progress and queued speech requests.
  73.  
  74.     IO REQUEST
  75.         io_Device       set by OpenDevice
  76.         io_Unit         set by OpenDevice
  77.         io_Command      CMD_FLUSH
  78.  
  79.     RESULTS
  80.         io_Error        always cleared
  81.  
  82.     BUGS
  83.  
  84.     SEE ALSO
  85.         exec.library/SendIO, exec.library/DoIO, exec/io.h
  86.  
  87. narrator.device/CMD_READ                       narrator.device/CMD_READ
  88.  
  89.     NAME
  90.         CMD_READ - Return the next different mouth shape from an 
  91.                associated write.
  92.  
  93.     FUNCTION
  94.         The read command of the narrator device returns mouth
  95.         shapes to the user.  The shape returned is guaranteed
  96.         to be differnt from the previously returned shape 
  97.         (allowing updating to be done only when something has
  98.         changed).  Each read request is associated with a 
  99.         write request by the pseudo-unit number assigned by
  100.         the OpenDevice call.  Since the first structure in
  101.         the read-mouth IORequest block (IORB) is a narrator
  102.         (write) IORB, this association is easily made by copying
  103.         the narrator IORB into the narrate_rb field fo the read IORB.
  104.         See the .h,i files.  If there is no write in progress
  105.         or in the device input queue with the same pseudo-unit
  106.         number as the read request, the read will be
  107.         returned to the user with an error.  This is also
  108.         how the user knows that the write request has 
  109.         finished and that s/he should not issue any more
  110.         reads.  Note that in this case the mouth shapes may
  111.         not be different from previously returned values.
  112.  
  113.     IO REQUEST
  114.         with the narrator_rb structure copied from the
  115.         associated write request except for:
  116.             io_Message  - message port for read request
  117.             io_Command  - CMD_READ
  118.             io_Error    - 0
  119.             width       - 0
  120.             height      - 0
  121.  
  122.     RESULTS
  123.         IORequest block fields set:
  124.             width  - mouth width in millimeters/3.67
  125.                      (division done for scaling)
  126.             height - mouth height in millimeters
  127.             shape  - compressed form of mouth shapes
  128.                      (internal use only)
  129.  
  130.     BUGS
  131.  
  132.     SEE ALSO
  133.         narrator.device/CMD_WRITE,
  134.         exec.library/DoIO, exec.library/SendIO, exec/io.h
  135.  
  136. narrator.device/CMD_RESET                 narrator.device/CMD_RESET
  137.  
  138.     NAME
  139.         CMD_RESET - Reset the device to a known state
  140.  
  141.     FUNCTION
  142.         Resets the device as though it has just be initialized.
  143.         Aborts all read/write requests whether active of enqueued.
  144.         Restarts device if it has been stopped.
  145.  
  146.     IO REQUEST
  147.         io_Device       set by OpenDevice
  148.         io_Unit         set by OpenDevice
  149.         io_Command      CMD_RESET
  150.  
  151.     RESULTS
  152.         io_Error        always cleared
  153.  
  154.     BUGS
  155.  
  156.     SEE ALSO
  157.         exec.library/SendIO, exec.library/DoIO, exec/io.h
  158.  
  159. narrator.device/CMD_START                 narrator.device/CMD_START
  160.  
  161.     NAME
  162.         CMD_START - Restarts the device after CMD_STOP
  163.  
  164.     FUNCTION
  165.         CMD_START restarts the currently active speech (if any)
  166.         and allows queued requests to start.
  167.  
  168.     IO REQUEST
  169.         io_Device       set by OpenDevice
  170.         io_Unit         set by OpenDevice
  171.         io_Command      CMD_START
  172.  
  173.     RESULTS
  174.         io_Error        always cleared
  175.  
  176.     BUGS
  177.  
  178.     SEE ALSO
  179.         exec.library/DoIO, exec.library/SendIO, exec/io.h
  180.  
  181. narrator.device/CMD_STOP                   narrator.device/CMD_STOP
  182.  
  183.     NAME
  184.         CMD_STOP  - Stops the device.
  185.  
  186.     FUNCTION
  187.         CMD_STOP halts the currently active speech (if any) and
  188.         prevents any queued requests from starting. 
  189.  
  190.     IO REQUEST
  191.         io_Device       set by OpenDevice
  192.         io_Unit         set by OpenDevice
  193.         io_Command      CMD_STOP
  194.  
  195.     RESULTS
  196.         io_Error        always cleared
  197.  
  198.     BUGS
  199.  
  200.     SEE ALSO
  201.         exec.library/DoIO, exec.library/SendIO, exec/io.h
  202.  
  203. narrator.device/CMD_WRITE                     narrator.device/CMD_WRITE
  204.  
  205.     NAME
  206.         CMD_WRITE - Send speech request to the narrator device
  207.  
  208.     FUNCTION
  209.         Performs the speech request.  If there is an associated read
  210.         request on the device input queue, write will remove it and
  211.         return an initial mouth shape to the user.
  212.  
  213.         Note: if you are going to be doing reads, 
  214.               the mouths parameter must be set to 1.
  215.  
  216.     IO REQUEST
  217.         narrator_rb request block:
  218.            ch_masks   - array of audio channel selection masks
  219.                        (see audio device documentation for
  220.                         description of this field)
  221.            nm_masks   - number of audio channel selection masks
  222.            mouths     - 0 if no mouths are desired
  223.                         1 if mouths are to be read
  224.            rate       - speaking rate
  225.            pitch      - pitch
  226.            mode       - pitch mode
  227.                         0 if natural mode
  228.                         1 if robotic mode
  229.            sex        - 0 if male
  230.                       - 1 if female
  231.            io_Message - message port
  232.            io_Command - CMD_WRITE
  233.            io_Data    - input string
  234.            io_Length  - length of input string
  235.            
  236.     RESULTS
  237.         The function sets the io_Error field of the IORB.  The
  238.         io_Actual field is set to the length of the input string
  239.         that was actually processed.  If the return code indicates
  240.         a phoneme error (ND_PhonErr), io_Actual is the position in
  241.         the input string where the error occured.
  242.  
  243.     BUGS
  244.  
  245.     SEE ALSO
  246.         narrator.device/CMD_READ, devices/narrator.h
  247.         exec.library/DoIO, exec.library/SendIO, exec/io.h
  248.         Audio device documentation.
  249.  
  250. narrator.device/OpenDevice
  251.  
  252.     NAME
  253.         OpenDevice - open the narrator device.
  254.  
  255.     SYNOPSIS
  256.         error = OpenDevice("narrator.device", 0 , iORequest , 0 );
  257.         D0                  A0                D0  A1          D1
  258.  
  259.     FUNCTION
  260.         The OpenDevice routine grants access to the narrator device.
  261.         OpenDevice checks the unit number, and if non-zero, returns
  262.         an error (ND_UnitErr).  If this is the first time the driver
  263.         has been opened, OpenDevice will attempt to open the audio
  264.         device and allocate the driver's static buffers.  If either
  265.         of these operations fail, an error is returned (see the .h,i
  266.         files for possible error return codes).  Next, OpenDevice
  267.         (done for all opens, not just the first one) initializes the
  268.         user's IORequest block (IORB).  Default values for sex, rate,
  269.         pitch, pitch mode, sampling frequency, and mouths are set in
  270.         the appropriate fields of the IORB.  Note that if users wish
  271.         to use non-default values for these parms, the values must
  272.         be set after the open is done.  OpenDevice then assigns a
  273.         pseudo-unit number to the IORB for use in synchronizing read
  274.         and write requests.  See the CMD_READ command for more details.
  275.         Finally, OpenDevice stores the device node pointer in the
  276.         IORB and clears the delayed expunge bit.
  277.  
  278.     INPUTS
  279.         deviceName - must be "narrator.device"
  280.         unitNumber - must be 0
  281.         iORequest  - a pointer to the user's IORequest block
  282.                      ( need not be initialized )
  283.         flags      - not used
  284.  
  285.     RESULTS
  286.         error - same as io_Error field of IORB
  287.  
  288.         IORequest block fields set:
  289.            rate    - 150 words/minute
  290.            pitch   - 110 Hz
  291.            mode    - Natural
  292.            sex     - Male
  293.            mouths  - Off
  294.            sampfreq - 22200
  295.            volume  - 64 (max)
  296.  
  297.     BUGS
  298.  
  299.     SEE ALSO
  300.         narrator.device/OpenDevice, narrator.device/CMD_READ,
  301.         exec/io.h
  302.  
  303.